Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

B

Default Parameters

Default parameters set and store values that affect the behavior of applications at run time.   Because their values are read each time an application runs, the parameters are the appropriate vehicle for recording user preferences and for inducing an application to exhibit alternate behavior that's useful during debugging.

Default parameters can be set in application code, on the command line that launches the application, or from a database stored in each user's home directory.  Parameter values are read at run time and can be written to the user's database using functions described in Chapter 3, ªCommon Classes and Functions.º  See NXRegisterDefaults() in that chapter for information on how to use default parameters within a program.  Parameters can also be written to the database, read, and removed using the dwrite, dread, and dremove command-line utilities.  

Both the names and the values of parameters are passed as character strings.  Thus a parameter that sets a numeric value will return a string of numeric characters rather than an integer.

Every pairing of a value to a parameter has an ªownerº that designates the domain in which the value is valid.  Typically, the owner is an application.  For  example, if you wanted to set the NXPaperType parameter to ªLegalº in the Lawyer application, you could use the dwrite utility on the command line as follows:

localhost> dwrite Lawyer NXPaperSize Legal

If the owner is ªGLOBALº (or ª-gº for dwrite), the value will apply to all applications except those that specifically own another value for the parameter.

The default parameters documented in this appendix affect the behavior of NEXTSTEP software.  Some can be set to aid debugging.  Some can be set to affect the way your application works.  Others should not be set, but can be read to get information about the user's preferences or the state of the application.

The parameters documented here are useful only in very specific situations, mainly for debugging.  For the most part, an application should not use any of them to record user preferences.  You must invent your own parameters to store user preferences for the applications you write.

At the beginning of each parameter description, there are two lines, one marked Value and the other Scope.  The Scope line reports the part of NEXTSTEP software that's affected by the default parameter.  The Value line reports the value the parameter has if it's not otherwise set.  Often the parameter will have another value when encountered in a running application, because it will have been set on the command line, in program code, by the Preferences application, by the system at startup, or by the Workspace Manager when it launches the application.  Don't rely heavily on the values stated.  

Debugging Parameters

The following parameters come in handy when debugging an application.  They're typically set on the command line to affect the behavior of an application during a debugging session.  They should not be written into anyone's defaults database (except perhaps your own for debugging purposes). 

NXAllWindowsRetained

Value:	NULL
Scope:	Application Kit

If set to any value, forces all buffered windows to be retained windows.  Since drawing is done directly into an on-screen retained window, you'll be able to watch PostScript code being rendered.  (Drawing is rendered in the buffer of a buffered window and then flushed to the screen.)

See also:  NXShowAllWindows

NXDebugLanguage

Value:	NULL
Scope:	Application Kit

If set to ªYESº, logs warnings when localized resources can't be found.  Warnings are issued when a resource file is missing or a requested string is absent from a string table.  The NXLogError() Application Kit function is used to record the error.

NXDefeatObjectLinkTimeouts

Value:	NULL
Scope:	Application Kit

If set to any value, removes timeouts for interprocess communications that implement data links.  Defeating these timeouts prevents processes from timing out as you're tracking down bugs in the debugger.

NXMallocDebug

Value:	ª0º
Scope:	Application Kit

Sets a value that's passed to malloc_debug() to control the amount of error checking done by malloc().  Valid values range from ª0º through ª31º, with ª31º being the highest level of error checking and ª0º being none.  See the UNIX manual page for malloc_debug() for specifics.

NXPSDebug

Value:	NULL
Scope:	Application Kit

If set to ªYESº, causes an alternate PostScript error-handling procedure to be installed.  This procedure produces more verbose debugging information than would otherwise be available, including the contents of the operand stack.

See also:  NXShowPS

NXShowAllWindows

Value:	NULL
Scope:	Application Kit

If set to any value, forces all windows to always be on-screen.  Windows that are normally hidden, such as windows that store images that are composited to other windows, will be visible as your program runs.

See also:  NXAllWindowsRetained

NXShowPS

Value:	NULL
Scope:	Application Kit

If set to any value, causes all PostScript code sent to the Window Server to also be written to the standard error stream.

See also:  NXPSDebug and NXSyncPS

NXSyncPS

Value:	NULL
Scope:	Application Kit

If set to any value, makes the application wait for the Window Server.  Whenever the application sends PostScript code to the Window Server, it will wait for the code to be executed before proceeding.  This results in error messages being more closely associated with the code that produced them.

See also:  NXShowPS and NXPSDebug

NXTraceEvents

Value:	NULL
Scope:	Application Kit

If set to any value, causes event-tracing information to be written to the standard error stream.

NXWindowDepthLimit

Value:	NULL
Scope:	Application Kit

Sets an upper limit on the depth of an application's windows.  Windows are created with a depth of two bits per pixel, but promote to a greater depth if it's required to display images in the window.  For example, color images would promote a window's depth, as would gray-scale images that use any shade of gray other than the four that are represented in two bits.

A window cannot be promoted to a depth greater than the limit.  Normally, the limit is set by what display screens are available.  A window won't be promoted to a depth greater than can be displayed on an available screen.  This parameter lets you further constrain the limit.  Valid settings are:

ªTwoBitGrayº
ªEightBitGrayº
ªTwelveBitRGBº
ªTwentyFourBitRGBº

The depth limit is set to the lesser of this value and the limit imposed by an available screen.  If the value is prefixed with ªTestº, as in ªTestTwentyFourBitRGBº, the limit will be set to the corresponding value even if it's greater than can be displayed on an available screen.

StripAfterLoading

Value:	ªYESº
Scope:	Workspace Manager

If set to ªNOº, prevents the Workspace Manager from stripping symbols from the modules it loads.  The symbols will therefore be available during debugging.  The Workspace Manager can load modules that implement Inspector panels for the contents of files.  See Chapter 19, ªWorkspace Manager,º for details.

Localization Parameters

These parameters are used in code that localizes an application (enables it to be used in various languages and various parts of the world).  Normally, the Preferences application sets these parameters globally for all applications.  You can modify them to affect the behavior of your particular application.

NXDate

Value:	ª%a %b %d %Yº
Scope:	Systemwide

Records the preferred format for presenting a date to the user.  The parameter value is a format string that can be passed to the ANSI C function strftime().

See also:  NXDateAndTime

NXDateAndTime

Value:	ª%a %b %d %H:%M:%S %Z %Yº
Scope:	Systemwide

Records the preferred format for presenting date and time information to the user.  The value of this parameter is a format string that can be passed to the ANSI C function strftime(), which translates date and time information recorded in a structure (of type struct tm) into a form that humans can read.  The format string tells strftime() what information is needed and how to present it.

Each formatting character refers to a particular type of information in a particular form.  For example, ª%aº means a short form of a weekday name (such as ªMonº and ªTueº in English or ªLunº and ªMarº in Spanish) and ª%Yº means the last two digits of a year (for example, ª92º for 1992).  See the specification for strftime() for information on all the formatting characters.

The current time can be obtained by time() and transformed into the proper structure by localtime().

See also:  NXDate and NXTime

NXLanguages

Value:	NULL
Scope:	Application Kit

Overrides the user's language preferences.  The value set should list language names, separated by semicolons, in the order of preference.  Use the systemLanguages method (defined in the Application class of the Application Kit), not this parameter, to discover the language preferences currently in force. 

NXTime

Value:	ª%H:%M:%S %Zº
Scope:	Systemwide

Records the preferred format for presenting a time to the user.  The parameter value is a format string that can be passed to the ANSI C function strftime().

See also:  NXDateAndTime

System Parameters

The following parameters pass information that is set by the system when an application is launched.  They shouldn't be modified by the application, but NXOpen and NXOpenTemp can be used on the command line to pass a file to the application.

NXAutolaunch

Value:	ªNOº
Scope:	Application Kit

If ªYESº, indicates that the Workspace Manager launched the application automatically at startup.

NXOpen

Value:	NULL
Scope:	Application Kit

Passes the name of a file for the application to open on launch.  When the user double-clicks a file to launch an application, the Workspace Manager uses this parameter to pass the file name to the application.

NXOpenTemp

Value:	NULL
Scope:	Application Kit

Passes the name of a temporary file for the application to open on launch.  The application should delete the file when it's through with it.

NXServiceLaunch

Value:	NULL
Scope:	Application Kit

If set to any value, indicates that the application wasn't launched directly by the user and therefore should not display an untitled document.  For example, the application might have been launched from the Services menu of another application, or it could have been launched to provide link data to another application.

User Preferences

The parameters in this section record user preferences.  Most are set by the Preferences application.  By reading the parameter and using the value that it contains, your application can be made to conform to the user's wishes.

NXBoldSystemFonts

Value:	NULL
Scope:	Application Kit

Records the user's preferred bold font for system uses.  This is the font used in window title bars.  The value is a semicolon-separated list of bold font names such as ªHelvetica-Boldº.  The first font in the list is the user's preference.  The other fonts in the list are alternatives if for some reason the user's preference can't be used.

You should use the boldSystemFontOfSize:matrix: method (defined in the Font class of the Application Kit) to get the user's preferred bold system font, rather than this parameter.

See also:  NXSystemFonts

NXMeasurementUnit

Value:	ªInchesº
Scope:	Application Kit

Records the user's preferred unit of measurement as set in the Preferences application.  Possible values are:

ªInchesº
ªCentimetersº
ªPointsº
ªPicasº

NXPaperType

Value:	ªLetterº
Scope:	Application Kit

Records the default paper size for a page layout.  A new PrintInfo object (defined in the Application Kit) will be set to this paper size.  The choices are:

ªLetterº	ªA3º
ªTabloidº	ªA4º
ªLegalº	ªA5º
ªLedgerº	ªB4º
ªExecutiveº	ªB5º

NXSystemFonts

Value:	NULL
Scope:	Application Kit

Records the user's preferred system fonts for such things as menu commands, button labels, and the text that appears in text fields.  This is normally set by the user in the Preferences application.  The value is a semicolon-separated list of font namesÐfor example, ªCourier;Times-Roman;Helveticaº.  The first font in the list is the user's preference.  The other fonts in the list are alternatives to it, if for some reason it can't be used.

You should use the systemFontOfSize:matrix: method (defined in the Font class of the Application Kit) to get the user's preferred system font, rather than this parameter.

See also:  NXBoldSystemFonts

Parameters for Expert Users

These parameters should be modified with care.  No application should use any of them to record user preferences.

NXCMYKAdjust

Value:	ªNOº
Scope:	Application Kit

If set to ªYESº, enables the Window Server to use an enhanced algorithm for rendering device-dependent CMYK colors on an RGB device (such as the screen).  The algorithm makes it possible for colors displayed on the screen to more closely match colors as they are printed.

This feature was added in Release 3.1, but it may make some applications built under previous releases behave strangely.  Therefore, it's turned off by default.

Applications built under the current release should be tested to make sure they work when NXCMYKAdjust is set to ªYESº.  This will eventually become the default.

NXFontsPaths

Value:	ª/NextLibrary/Fonts/:~/Library/Fonts/:/LocalLibrary/Fonts/º
Scope:	Application Kit

Records the search path for fonts.  Applications can modify this path to include other directories if need be.  Pathnames should end in a slash (ª/º) and be separated by a colon.

NXHost

Value:	NULL
Scope:	Application Kit

If set to the name of a machine on the command line, causes the application to connect to the Window Server running on that machine. The application's user interface will appear on the display attached to the named host.

NXIsJournalable

Value:	ªNOº
Scope:	Application Kit

If set to ªYESº, makes the application journalable.  Through the Application Kit's journaling mechanism, other applications will be able to record the events the application receives.  This parameter sets the default value returned by the isJournalable method defined in the Application class of the Application Kit.  It can be overridden by the setJournalable: method.

NXNetTimeout

Value:	ª60º
Scope:	Application Kit

Records how long, in seconds, the application will wait for its communications with other processes to succeed before giving up.

NXObjectLinkUpdateMode

Value:	ª2º
Scope:	Application Kit

Records the default update mode for newly created data links.  Permitted values range from ª1º through ª4º:

ª1º	The data link is updated continuously.
ª2º	The data link is updated when the source document for the link is saved.
ª3º	The data link is updated only when the user requests it in the Link Inspector.
ª4º	The data link is never updated.

NXUseTrueGrays

Value:	NULL
Scope:	Application Kit

If set to any value, causes the Application Kit to set a color value for intermediate grays rather than use a pattern.  The Kit sometimes uses patterns to keep windows from becoming deeper than they need to be.

For example, when drawing standard user interface devices like scroll bars, the Application Kit normally uses a pattern to represent a 50% gray value midway between black and white.  Using the pattern prevents the window displaying the device from promoting from a depth of two bits per pixel to a greater depth capable of showing the intermediate gray as a true color.

When creating artwork from an on-screen display, using a true gray may avoid moire patterns in the result.

Compatibility Parameters

The following parameters are ones that users can set to make applications that were developed with an earlier version of NEXTSTEP software work as desired under Release 3.  They should be set as individual preferences, not in application code.  New applications and updated versions of existing ones should be developed to work with the latest version of NEXTSTEP software.

NXClickForHelpEnabled

Value:	ªYESº
Scope:	Application Kit

If set to ªNOº, disables click-for-help.  On keyboards that don't have a dedicated Help key, the click-for-help feature is controlled by a combination of the Control and Alternate modifier keys.  Users of applications that use Control-Alternate combinations for something else may wish to disable this feature.

This parameter sets the default value returned by the isClickForHelpEnabled method defined in the NXHelpPanel class of the Application Kit.

NXColorCalibrateLevelOneOps

Value:	ªYESº
Scope:	Application Kit

If set to ªNOº, turns off all forced calibration of device-dependent PostScript color operators.  Device-independent color is a feature of PostScript Level 2.  NEXTSTEP Release 3 incorporates PostScript Level 2 and uses a calibrated color space for drawing.  When printing, all device-dependent Level 1 operators used in applications based on previous NEXTSTEP releases are reinterpreted to the calibrated color space.  (Level 1 operators used in applications based on the current release are not affected.)  Setting this parameter to ªNOº defeats this feature.

The most likely compatibility problem to occur while this parameter is ªYESº is that imported EPS (encapsulated PostScript) files may print with the wrong colors.

NXSave2.0Compatibly

Value:	ªNOº
Scope:	Application Kit

If set to ªYESº, has the Application Kit write data to a typed stream in a way that's compatible with the previous NEXTSTEP release.

When writing data to a typed stream, the Application Kit is able to include informationÐnotably about PANTONEâColorsÐthat wasn't available in previous versions of NEXTSTEP software.  This new information may not be understood when read by applications that haven't yet been updated to the new release.

When this parameter is ªYESº, the new information won't be written to the stream and will consequently be lost.  For example, PANTONE Color names won't be saved.

NXSecureAppListenerPorts

Value:	ªNOº
Scope:	Application Kit

If set to ªYESº, has the Application Kit secure the ports of applications built under Releases 1 and 2 so that they're not accessible to applications running on other machines.  This makes applications built under those earlier releases behave like applications built under more recent releases.

In Release 3, the Kit registered the ports of all applications under private and unique names; applications running on the same machine could communicate with each other, but applications running on different machines couldn't, unless specifically designed to do so.  This change broke applications that were built under prior releases and that required network communication.

Therefore, beginning with Release 3.1, only applications built under Release 3 and later have their ports registered under secure names.  This means that, by default, applications built under the earlier releases won't be secure.  Setting the NXSecureAppListenerPorts parameter to ªYESº secures them.  It forces the Kit to treat them the same as applications built under Release 3. 

NXSmartNamedColorConversion

Value:	ªYESº
Scope:	Application Kit

If set to ªNOº, turns off the Application Kit's algorithms for finding the CMYK values for nonCMYK and forces it to use a simple conversion instead.

Before Release 3.1, Kit functions like NXConvertColorToCMYK() and NXCyanComponent() found the CMYK values of colors by simply converting the RGB values used on the screen to CMY.  Since there was no K (black) component, the resulting values weren't of much use.  Beginning with Release 3.1, the Kit tries to find the CMYK values of named colors (such as PANTONE colors) by looking them up in the DefaultCMYK table, rather than by RGB conversion.  This parameter can be used to restore the previous behavior.

NXUseCalibratedColor

Value:	ªYESº
Scope:	Application Kit

If set to ªNOº, turns off all generation of calibrated colors when printing.  If the colors an application displays on the screen or produces from the printer seem wrong or substantially different from what they were under the previous release, and setting the NXColorCalibrateLevelOneOps parameter to ªNOº for the application doesn't seem to help, setting this parameter to ªNOº should fix the problem.